home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / shazam.exe / AINTRO.DOC < prev    next >
Encoding:
Text File  |  1992-09-01  |  15.1 KB  |  405 lines
  1.                              ************
  2.                              INTRODUCTION
  3.                              ************
  4.  
  5. SHAZAM lets you define the entire interface of a Turbo Vision
  6. application in a simple ASCII file.
  7.  
  8. With a few keywords and a easy syntax, you can define and test
  9. anything from a simple test program to the TP 6.0 IDE, including
  10. online help, hints and context-sensitive StatusLines.
  11.  
  12. You only need the [ SUBMENU ] and [ STATUS ] keywords to develop an
  13. interface.  Other keywords and switches give you control over every
  14. aspect of how a program is generated.
  15.  
  16. You can develop and maintain Turbo Vision software using SHAZAM, too,
  17. not just generate interfaces.  Use the Dialog Editor to paint
  18. screens and the [ DIALOG ] keyword to include them; the [ UNIT ]
  19. keyword for automatic overlays and registration.
  20.  
  21. By flipping switches, you can change your program from pure code (for
  22. fast development) to a fully resourced, overlaid program with
  23. swap-to-disk capability for EXEC calls.
  24.  
  25. Keywords and switches are covered later.  First, let's take a look at
  26. the process of creating a program.  This will help you understand
  27. what the keywords and switches are, and why they exist.
  28.  
  29.  
  30.  
  31.                            ***************
  32.                            THE BIG PICTURE
  33.                            ***************
  34.  
  35.    Application Elements                    Program Elements
  36.  
  37.                        *.HLP                    *.EXE
  38.   *.DLG         *.DEF  *.TXT        *.REZ       *.OVR    *.$$$
  39.  ┌───────┐     ┌──────┬──────┐     ┌───────────┬────────┬────────┐
  40.  │       │     │Menus │Online│     │           │Program │Unitize │
  41.  │Dialogs│     │Status│ Help │     │ Resources │   &    │   &    │
  42.  │       │     │Hints │      │     │           │Overlays│ExecSwap│
  43.  └───┬───┘     └──┬───┴─┬──┬─┘     └─────┬─────┴───┬────┴───┬────┘
  44.      │            ├─────┘  │             └─────────┼────────┘
  45.      │            │        │                       │
  46.  ╔═══╧══╗      ╔══╧═══╗ ╔══╧═════╗            ╔════╧════╗
  47.  ║Dialog║      ║ Text ║ ║  Help  ║            ║   Code  ║
  48.  ║Editor║      ║Editor║ ║Compiler║            ║Generator║
  49.  ╚═══╤══╝      ╚═══╤══╝ ╚════╤═══╝            ╚════╤════╝
  50.      └─────────────┴────┬────┴─────────────────────┘
  51.                         │
  52.                    ▐▀▀▀▀▀▀▀▀▌
  53.                    ▐ SHAZAM ▌
  54.                    ▐▄▄▄▄▄▄▄▄▌
  55.  
  56.  
  57. This little diagram might make you wonder:  Can SHAZAM create your
  58. application as a fully resourced program with overlays, using
  59. multiple and/or foreign language sets of MenuBars, Context-sensitive
  60. StatusLines, Hints and Dialogs, compile Help Text, ensure updated
  61. resource values and by-the-way encapsulate everything so we can
  62. swap-to-disk for EXEC calls with minimum memory overhead?
  63.  
  64. Yes.
  65.  
  66. Load any example definition, then press "Ctrl-F9" to run it.
  67.  
  68.  
  69.  
  70.                           ******************
  71.                           EVOLVING A PROGRAM
  72.                           ******************
  73.  
  74. Let's look at the how you create a program by hand, then using SHAZAM.
  75.  
  76.  
  77. BY HAND
  78. =======
  79. First, we need an interface - something to start with.  Create a
  80. MenuBar, match up all those "NIL" and "Parentheses".  Now, for each
  81. interface item (cmXX), extend HandleEvent to call a dummy routine and
  82. create the routine (a window or MsgBox), so we can see something
  83. happen.  Next, figure out a help context for the drop-down menus, so
  84. we can at least have hints -- oops, gotta extend a new StatusLine
  85. object, so the hints show up.  Let's plug-in the "HelpFile" unit and
  86. dummy up some online Help, so the "F1" does something.  Look-up and
  87. re-use the help contexts we already defined -- oops, we don't need to
  88. define them anymore, the help compiler does it for us, so take'em
  89. out.  Don't forget to extend "GetPalette", to avoid the RED + WHITE +
  90. BLINK when help pops up.
  91.  
  92. Normally, you'd have to do all the above by hand, even for a three
  93. line program.  A partial list of the things you need to hand-code:
  94.  
  95.        MenuBar - Items & SubMenus
  96.     StatusLine - Items & Context ranges
  97.                  (PNewStatusLine w/Load & Store, for hints/resources)
  98.           cmXX - Command constant names & values
  99.         Params - MenuBar shortcuts
  100.          Hints - One-Liners for MenuBar & Dialog controls
  101.           kbXX - Which keyboard consta
  102.           hcXX - help context
  103.  
  104.  
  105. Using SHAZAM
  106. ============
  107. The following statements do ALL the above, in about 60 seconds:
  108.  
  109.     [ SUBMENU ] File        ;;file management
  110.     Open                    ;;open a new file
  111.     Save                    ;;save text in current window
  112.  
  113. Try a "copy & paste" of the three lines above into a file named
  114. SAMPLE.DEF, then press the Ctrl-F9 key to run the example.  You'll
  115. note that SHAZAM does a number of little "extras", such as adding
  116. context sensitive StatusLines where needed (these "extras" can be
  117. controlled via switches or the SETUP|Code dialog).
  118.  
  119. By now, you're probably got the idea that the distance from program
  120. "Conception to Construction" just got shorter!  As soon as you run
  121. through the ADEMO*.DEF series, putting meat on the bones of your
  122. applications is going to get a lot easier.  You should be able to get
  123. a new interface up & running almost as fast as you can think it up.
  124.  
  125.  
  126.  
  127.                              ************
  128.                              FLESH IT OUT
  129.                              ************
  130.  
  131. If you look at the source code for any generated definition, you'll
  132. see that command constants, help contexts and "dummy routines" are
  133. generated by SHAZAM for each Menu or Status item.  An entry is made
  134. in the generated HandleEvent, with each "cmXX" symbol matching a call
  135. to an "hdXX" routine of the same name.
  136.  
  137. Look at the *.HE file from any generated example.
  138.  
  139. Unless you say otherwise, the matching "hdXX" is a "dummy routine",
  140. created by SHAZAM, so generated programs will compile (and do
  141. something).
  142.  
  143. Of course, if you could make the Application^.HandleEvent call your
  144. own code, instead of dummy routines, SHAZAM could be used for actual
  145. programs, to develop and maintain software.
  146.  
  147. Somehow, you have to signal SHAZAM that an element of a Menu/Status
  148. item is either the real thing or must be dummied up.  That's where
  149. keywords and/or symbols come into play.
  150.  
  151.  
  152. MENU/STATUS ITEMS
  153. -----------------
  154. A quick glossary of terms:
  155.  
  156.     cmXX - A command constant/symbol
  157.     kbXX - A keyboard constant/symbol
  158.     hdXX - A HandlecommanD routine (actual or dummy)
  159.     hbXX - A HandleBroadcast routine
  160.     hcXX - A help context constant/symbol (MENU only)
  161.  
  162.  
  163. You can signal that an item is "real" by
  164.  
  165.     1.  Auto-scan of related *.EVT file
  166.     2.  Keywords - [ INTERNAL ] and [ EXTERNAL ]
  167.     3.  Symbols - "^^" (internal) and "%%" (external)
  168.  
  169.  
  170. AUTO-SCAN
  171. ---------
  172. If the matching *.EVT files exists, it is scanned for command and/or
  173. broadcast routines which have "hd" or "hb" prefixes.  If found, a
  174. matching "cmXX" is created, and entries will be made to the generated
  175. HandleEvent.
  176.  
  177. Each "hdXX" is added to HandleEvent, under the "evCommand" mask; look
  178. at a generated *.HE file and you will find a "HandlecommanD" section.
  179.  
  180. Each "hbXX" is added to HandleEvent, under the "evBroadcast" mask.
  181. Generate BCAST.DEF and look at "HandleBroadcast" in the BCAST.HE file.
  182.  
  183. This works dandy, since these are always at the Application level.
  184. But you may want to move code into units or include files, so we need
  185. another way to "reserve" names for cmXX, hdXX and hbXX symbols.
  186.  
  187.  
  188.  
  189. [ INTERNAL ] or [ EXTERNAL ]
  190. ----------------------------
  191. Remember, when a program is generated, each "XX" name generates a
  192. matched pair of "cmXX" and "hdXX" for HandleEvent.  And it's a given
  193. that any MenuBar, MenuBox or StatusLine item is going to be handled
  194. by either the Application or a TView descendant.
  195.  
  196. You need to decide:  Is the event handled by the Application or an
  197. object?  If by an object, like TFileEditor, it's [INTERNAL].  If by
  198. the Application, it's [EXTERNAL].
  199.  
  200. [ INTERNAL ] stuff we don't have to worry about, other than to tell
  201. SHAZAM that no cmXX or hdXX routines need to be created.
  202.  
  203. [ EXTERNAL ] routines are what we're going to be working with.  They
  204. can be anywhere -- in an include file or a unit.  You'll find some
  205. useful "[ EXTERNAL ]" routines in the GENERAL unit (see GEVENT.INT)
  206. for common functions like "hdTile", "hdSaveDesktop", etc.
  207.  
  208. With either keyword, all you're doing is making a "reservation" for a
  209. pair of "cmXX" and "hdXX" names.  Just make a list under each
  210. keyword.  The equivalent symbols, "^^" for [ INTERNAL ] and "%%" for
  211. [ EXTERNAL ], can be used right in the definition file.
  212.  
  213.  
  214. EXAMPLES
  215. --------
  216. Assuming we have the routine "hdOpen" in an include file or a unit,
  217. the following [ EXTERNAL ] examples are identical:
  218.  
  219.                             SYMBOL EXAMPLE
  220. [submenu] file
  221. %%Open
  222. Save
  223.  
  224.                            KEYWORD EXAMPLE
  225. [external]
  226. Open
  227.  
  228. [submenu] file
  229. Open
  230. Save
  231.  
  232.  
  233. Assuming we have an object which has a built-in "Save" function, such
  234. as a TFileEditor, the following [ INTERNAL ] examples are identical:
  235.  
  236.                             SYMBOL EXAMPLE
  237. [submenu] file
  238. Open
  239. ^^Save
  240.  
  241.                            KEYWORD EXAMPLE
  242. [internal]
  243. Save
  244.  
  245. [submenu] file
  246. Open
  247. Save
  248.  
  249.  
  250.                            *.EVT REVISITED
  251.  
  252. Remember that this file is scanned for prefixed routines.  The
  253. HandlecommanD (hdXX) were covered earlier; now let's look at
  254. HandleBroadcast (hbXX).
  255.  
  256. The [ BROADCAST ] keyword
  257. =========================
  258. By nature, broadcasts are never called directly from a Menu or Status
  259. item.  They are either standard, such as "hbCommandSetChanged" or
  260. defined & called by you (or your objects) via the Message function.
  261.  
  262. If a routine name prefixed with "hb" is found, it is added to the
  263. generated HandleEvent under "HandleBroadcast".
  264.  
  265. If you want the code to be in an include file or a unit, you use the
  266. [ BROADCAST ] keyword to signal that the routine exists, but is not
  267. in the *.EVT file.  The "HandleBroadcast" call will be made.
  268.  
  269. See BCAST.DEF for details.
  270.  
  271.  
  272.  
  273.                             **************
  274.                             NAMES OF FILES
  275.                             **************
  276.  
  277. Using SHAZAM, there are two types of files:
  278.  
  279.     [X] Custom - What you create and maintain
  280.     [X] Generated - by SHAZAM
  281.  
  282. By default, all components and generated files are kept in separate
  283. include files.  You can use the SETUP dialog to put all code into a
  284. single *.PAS file.
  285.  
  286.  
  287. CUSTOM FILES
  288. ============
  289. These are the files which you create and maintain.  If you've loaded
  290. any of the more advanced definitions (*.DEF), you'll note that when
  291. Desktop is empty, all these files are loaded for you; this can be
  292. changed with the SETUP|IDE dialog.  Also, the system menu contains
  293. options to load and clear these files from the Desktop.
  294.  
  295.     *.DEF - the definition file
  296.     *.INC - general purpose include file
  297.     *.VIR - your application methods
  298.     *.EVT - event routines for HandleBroadcast & HandleCommand
  299.     *.TXT - Help text (optional)
  300.     *.DLG - Dialog Editor files (interactive)
  301.  
  302.  
  303. GENERATED FILES
  304. ===============
  305. These are organized as primary and secondary files.  Order and
  306. placement vary, depending on whether your program is currently a
  307. code, resource or combination-type application.
  308.  
  309.    *.pas - the program
  310.     *.OV - list of units to overlay
  311.  *_I.pas - initialization for names, overlays & memory remapping.
  312.     *.KB - kbXX used by the definition, plus kbCtrl? added by SHAZAM
  313.     *.CM - cmXX (command constants) generated by SHAZAM
  314.     *.RZ - "RezFile" object, plus code to open & close resource file
  315.  
  316.  *_X.pas - hcXX symbols, from Help Compiler
  317.  
  318.  *_U.pas - unitized application
  319.     *.US - list of units for USES clause
  320.     *.OB - declaration of the application object
  321.            *.MB - MenuBar(s) (CODE only)
  322.            *.SL - StatusLine(s) (CODE only)
  323.            *.HN - Hint set(s) (CODE only)
  324.     *.GE - GetEvent, GetPalette and OutOfMemory methods
  325.    *.INC - CUSTOM COMPONENT
  326.    *.VIR - CUSTOM COMPONENT
  327.     *.HE - HandleEvent method (HandleBroadcast & HandleCommand)
  328.            *.EVT - CUSTOM COMPONENT
  329.             *.EV - Dummy routines
  330.     *.DC - documentation, summary of generated application
  331.  
  332.  
  333. RESOURCES
  334. =========
  335. If the application uses resources, the Menu, Status and Hint elements
  336. are separated into UNITS, to allow construction of larger, more
  337. detailed interfaces.  The following are created:
  338.  
  339.  *_R.pas - program to create/update resources
  340.  *_M.pas - unit for MenuBar(s)
  341.            *.MB - MenuBar(s) (REZ only)
  342.  *_S.pas - unit for StatusLine(s)
  343.            *.SL - StatusLine(s) (REZ only)
  344.  *_H.pas - unit for Hint set(s)
  345.            *.HN - Hint set(s) (REZ only)
  346.  
  347.  
  348.  
  349.                            ****************
  350.                            COMPILER SYMBOLS
  351.                            ****************
  352.  
  353. The following compiler symbols are automatically added by SHAZAM:
  354.  
  355.   {$DEFINE defname} - name of *.DEF file
  356.      {$DEFINE code} - if all framework elements are set to "code"
  357.  {$DEFINE resource} - if all framework elements are set to "REZ"
  358.  {$DEFINE execswap} - if the ExecSwap ("/x+") option is set
  359.  
  360.  
  361.          ----------------end-of-author's-documentation---------------
  362.  
  363.                          Software Library Information:
  364.  
  365.                     This disk copy provided as a service of
  366.  
  367.                            Public (software) Library
  368.  
  369.          We are not the authors of this program, nor are we associated
  370.          with the author in any way other than as a distributor of the
  371.          program in accordance with the author's terms of distribution.
  372.  
  373.          Please direct shareware payments and specific questions about
  374.          this program to the author of the program, whose name appears
  375.          elsewhere in  this documentation. If you have trouble getting
  376.          in touch with the author,  we will do whatever we can to help
  377.          you with your questions. All programs have been tested and do
  378.          run.  To report problems,  please use the form that is in the
  379.          file PROBLEM.DOC on many of our disks or in other written for-
  380.          mat with screen printouts, if possible.  PsL cannot debug pro-
  381.          programs over the telephone, though we can answer questions.
  382.  
  383.          Disks in the PsL are updated  monthly,  so if you did not get
  384.          this disk directly from the PsL, you should be aware that the
  385.          files in this set may no longer be the current versions. Also,
  386.          if you got this disk from another vendor and are having prob-
  387.          lems,  be aware that  some files may have become corrupted or
  388.          lost by that vendor. Get a current, working disk from PsL.
  389.  
  390.          For a copy of the latest monthly software library newsletter
  391.          and a list of the 4,000+ disks in the library, call or write
  392.  
  393.                            Public (software) Library
  394.                                P.O.Box 35705 - F
  395.                             Houston, TX 77235-5705
  396.  
  397.                                 1-800-2424-PSL
  398.                              MC/Visa/AmEx/Discover
  399.  
  400.                           Outside of U.S. or in Texas
  401.                           or for general information,
  402.                               Call 1-713-524-6394
  403.  
  404.  
  405.